---
title: "App Service"
description: "Core service for managing third-party applications in MentraOS"
---

## Overview

The AppService (`app.service.ts`) is the central registry and management system for all third-party applications (TPAs) in MentraOS. It handles app discovery, authentication, webhook interactions, and maintains the app ecosystem.

## Location

`packages/cloud/src/services/core/app.service.ts`

## Key Responsibilities

### 1. App Registry Management
- Maintains both system apps and user-installed apps
- Provides app discovery and retrieval
- Manages app metadata and configurations

### 2. App Authentication
- Validates API keys for app connections
- Generates and manages app tokens
- Handles app-specific security

### 3. Webhook Orchestration
- Manages webhook endpoints for apps
- Handles session lifecycle webhooks (start/stop)
- Implements retry logic for failed webhooks
- Supports tool call webhooks for app interactions

### 4. App State Management
- Tracks app states across user sessions
- Manages app installation and permissions
- Handles pre-installed app configurations

## Core Methods

### `getAllApps(userId?: string)`
Retrieves all available apps for a user, combining:
- System apps (hardcoded for reliability)
- User-installed apps from MongoDB
- Pre-installed apps based on environment

```typescript
const apps = await appService.getAllApps('user@example.com');
// Returns array of AppI objects
```

### `getApp(packageName: string)`
Fetches a specific app by its package name.

```typescript
const app = await appService.getApp('com.translator.app');
```

### `validateApiKey(packageName: string, apiKey: string)`
Validates an app's API key for authentication.

```typescript
const isValid = await appService.validateApiKey(
  'com.translator.app',
  'app_api_key_here'
);
```

### `generateAppToken(packageName: string, userId: string, sessionId: string)`
Creates a JWT token for app authentication.

```typescript
const token = await appService.generateAppToken(
  'com.translator.app',
  'user@example.com',
  'session-123'
);
```

## Webhook System

### Session Webhooks
Apps can register webhooks to be notified of session events:

#### Start Webhook
```typescript
// Called when app starts
{
  url: 'https://app.example.com/webhook/start',
  headers: { 'X-App-Secret': 'secret' }
}

// Payload sent:
{
  type: 'session.start',
  sessionId: 'session-123',
  userId: 'user@example.com',
  capabilities: { /* device capabilities */ }
}
```

#### Stop Webhook
```typescript
// Called when app stops
{
  type: 'session.stop',
  sessionId: 'session-123',
  reason: 'user_requested' | 'session_ended' | 'error'
}
```

### Tool Call Webhooks
Apps can expose tools that the system can call:

```typescript
// Tool webhook request
{
  type: 'tool.call',
  toolName: 'translate',
  parameters: {
    text: 'Hello',
    targetLanguage: 'es'
  },
  sessionId: 'session-123'
}

// Expected response
{
  success: true,
  result: 'Hola'
}
```

## Pre-installed Apps

The service manages different app installation tiers:

### Production Apps
```typescript
const PRE_INSTALLED = [
  "com.augmentos.livecaptions",
  "cloud.augmentos.notify", 
  "cloud.augmentos.mira"
];
```

### Debug/Development Apps
Additional apps loaded in development mode:
- Testing apps
- Developer tools
- Experimental features

## App State Tracking

The service maintains in-memory app states:

```typescript
// Structure: userId -> packageName -> AppState
private appStates = new Map<string, Map<string, AppState>>();
```

States include:
- `INITIALIZING`: App is starting up
- `CONNECTED`: App is ready
- `RESURRECTING`: App is reconnecting
- `STOPPED`: App has been terminated

## Integration with Other Services

### With AppManager
- AppService provides app metadata
- AppManager handles runtime lifecycle

### With SessionService
- Apps are associated with user sessions
- Session events trigger app webhooks

### With MongoDB
- App definitions stored in `apps` collection
- User app installations tracked in `users` collection

## Configuration

### Environment Variables
- `SYSTEM_DASHBOARD_PACKAGE_NAME`: Package name for system dashboard
- `NODE_ENV`: Determines if debug apps are loaded
- `DEBUG_APPS`: Force load debug apps in production

### System Apps
Currently hardcoded for reliability, includes:
- Dashboard app
- System utilities
- Core functionality apps

## Security Considerations

1. **API Key Hashing**: All API keys are hashed before storage
2. **Webhook Secrets**: Optional endpoint secrets for webhook verification
3. **Token Expiration**: App tokens have limited lifetime
4. **Permission Validation**: Apps must declare required permissions

## Future Improvements

1. **Database Migration**: Move system apps to database
2. **Service Splitting**: Separate into:
   - `appstore.service.ts`: App store functionality
   - `developer.service.ts`: Developer portal features
   - `tools.service.ts`: Tool execution system
3. **Caching Layer**: Add Redis for app metadata caching
4. **Webhook Queue**: Implement proper webhook queue with retries

## Usage Example

```typescript
// In AppManager when app connects
const app = await appService.getApp(packageName);
if (!app) {
  throw new Error('App not found');
}

// Validate API key
const valid = await appService.validateApiKey(packageName, apiKey);
if (!valid) {
  throw new Error('Invalid API key');
}

// Generate session token
const token = await appService.generateAppToken(
  packageName,
  userId,
  sessionId
);

// Send start webhook
await appService.sendWebhook(app.webhooks?.start, {
  type: 'session.start',
  sessionId,
  userId
});
```

## Best Practices

1. **Always validate app existence** before operations
2. **Use try-catch for webhook calls** - they can fail
3. **Log webhook failures** but don't crash the session
4. **Cache app metadata** when possible
5. **Validate permissions** before granting access